Tutorial 1: Adding a new monatomic species entry to your local data store, the manual way

If you would like to do calculations using a plasma species that you haven’t used before, you will need to generate a minplascalc data entry for it first. You only need to do this once - minplascalc will store the species data in a plain-text file formatted using JSON syntax, and it will then be available for use in any of your future calculations.

For monatomic species minplascalc has built-in readers for handling data obtained from the energy levels section of NIST Atomic Spectra Database, which can be found at http://physics.nist.gov/PhysRefData/ASD/levels_form.html. The landing page looks like this.

You must then specify the atom or ion that you want to retrieve energy level information for. Let’s get the data for the singly-charged oxygen cation species O+, which is “O II” in spectrographic terminology. Enter the identifier in the Spectrum field on the form:

Make sure you set Level Units to “cm-1”, Format Output to “ASCII (text)”, and uncheck everything in the output section except Level and J, like this:

Click the Retrieve Data button. You should see a page with the energy levels listed in a plain-text table. Click and drag to select everything from the first energy level line down to the last one before the first ionisation energy entry (these have no J value and are separated in boxes of ASCII dashes). While you’re there, make a note of the ionisation energy value.

Copy and paste the selected content into a temporary text file. This has already been done for the oxygen cation, and the raw NIST data file is located at minplascalc/data/species_raw/nist_O+. Running the following code snippet will add a data entry for the O+ ion to minplascalc:

import minplascalc as mpc

energylevels = mpc.read_energylevels(open("../minplascalc/data/species_raw/nist_O+"))

species_data = mpc.build_monatomic_species_json(
    name="O+",
    stoichiometry={"O": 1},
    molarmass=0.0159994,
    chargenumber=1,
    ionisationenergy=283270.9,
    energylevels=energylevels)

with open('O+.json', 'w') as jf:
    mpc.json.dump(species_data, jf, indent=4)

What’s happening here? First we import the minplascalc package, then we read the energy levels from the NIST data file, then we call the buildMonatomicSpeciesJSON function to build species data dictionary for us and save the result as a JSON file.

The function takes as arguments the species name (which is also used as the data entry’s associated file name), a small dictionary describing the elemental stoichiometry of the species (in this case a single oxygen atom), the molar mass in kg/mol, the charge on the species in units of the fundamental charge (in this case 1 because O+ is singly charged), the ionisation energy of the species in cm-1, and the path to the energy level text file we just generated from the NIST site. Internally to minplascalc the function assembles the species information into a Python dictionary format. We then write out the JSON file called “O+.json” on the path you’re running this notebook from.

After this process it will be possible to create an O+ species object in any minplascalc calculation by importing it using either the explicit path to the JSON file, or (preferably) just the name of the species provided the JSON file is stored in any of the standard minplascalc data paths - see later tutorials for examples.